feat: Add Node.js bindings via napi-rs by davidfestal · Pull Request #253 · oras-project/rust-oci-client

davidfestal · 2026-03-31T12:29:40Z

Introduces Node.js bindings for the rust-oci-client using napi-rs, enabling Node.js applications to interact with OCI registries.

Features:

17 OciClient methods: pull, push, manifests, blobs, tags, referrers
Authentication helpers: anonymous, basic, bearer
Platform resolver configuration via os/arch/variant filter
Full TypeScript definitions auto-generated

Supported platforms (7 targets):

macOS x86_64 and ARM64
Linux x86_64 and ARM64 (glibc)
Linux x86_64 and ARM64 (musl/Alpine)
Windows x86_64

CI/CD:

Build and test workflows for all platforms
Publish workflow for NPM releases
Node.js 22 and 24 support
Integration tests with Zot registry

Note:

In order to allow the publishing of the Javascript bindings to NPMJS, a NPM_TOKEN secret will be required in this repository.

Assisted-by: Cursor

Introduces Node.js bindings for the rust-oci-client using napi-rs, enabling Node.js applications to interact with OCI registries. Features: - 17 OciClient methods: pull, push, manifests, blobs, tags, referrers - Authentication helpers: anonymous, basic, bearer - Platform resolver configuration via os/arch/variant filter - Full TypeScript definitions auto-generated Supported platforms (7 targets): - macOS x86_64 and ARM64 - Linux x86_64 and ARM64 (glibc) - Linux x86_64 and ARM64 (musl/Alpine) - Windows x86_64 CI/CD: - Build and test workflows for all platforms - Publish workflow for npm releases - Node.js 22 and 24 support - Integration tests with Zot registry Assisted-by: Cursor Signed-off-by: David Festal <dfestal@redhat.com>

davidfestal · 2026-03-31T12:38:26Z

cc @TerryHowe This is the work I briefly told you about last week at KubeCon EU when discussing at the ORAS booth.

davidfestal · 2026-03-31T12:40:07Z

Before opening this PR, the result of the bindings publish workflow has already been pushed from my fork to my personal scope on NPMJS: @dfatwork/oci-client.
It can be easily tested from there in any Node.js project.

davidfestal · 2026-03-31T14:55:45Z

cc @sabre1041

TerryHowe · 2026-03-31T17:08:01Z

cc @TerryHowe This is the work I briefly told you about last week at KubeCon EU when discussing at the ORAS booth.

Ah, okay. Thanks. I'm not a maintainer on this project though, so they will need to chime in.

Copilot

Pull request overview

Adds a new napi-rs-based Node.js/TypeScript binding package for oci-client, plus CI workflows to build/test/publish prebuilt binaries across major platforms.

Changes:

Introduces a new bindings/nodejs workspace crate exposing an OciClient N-API surface (auth/config/manifest/blob APIs + TS types).
Adds Node-side tooling (Yarn v4, version sync script, TS config, tests including mock registry + Zot integration).
Adds GitHub Actions workflows for multi-target Node build/test, npm publish, and wires release flow to run Node checks.

Reviewed changes

Copilot reviewed 22 out of 23 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
Cargo.toml	Converts repo to a Cargo workspace and centralizes shared package/dependency metadata.
bindings/nodejs/yarn.lock	Adds Yarn lockfile for Node binding toolchain dependencies.
bindings/nodejs/tsconfig.json	TypeScript compiler settings for the Node bindings package.
bindings/nodejs/src/lib.rs	Implements the N-API Rust bindings (client/config/auth/types/manifests/constants).
bindings/nodejs/scripts/sync-version.js	Syncs Node package version to Rust workspace version.
bindings/nodejs/scripts/fix-const-enums.js	Post-processes generated `.d.ts` to avoid `const enum` declarations.
bindings/nodejs/README.md	Documents installation/usage and exposed APIs for Node consumers.
bindings/nodejs/package.json	Defines the npm package, scripts, napi targets, and dev dependencies.
bindings/nodejs/Cargo.toml	New Rust crate manifest for the Node bindings (`cdylib`) and feature wiring.
bindings/nodejs/build.rs	Sets up `napi-build` for generating bindings at build time.
bindings/nodejs/.yarnrc.yml	Configures Yarn to use `node-modules` linker.
bindings/nodejs/.gitignore	Ignores generated bindings artifacts, build outputs, and node_modules.
bindings/nodejs/.gitattributes	Sets text/binary attributes and marks generated binding outputs as non-detectable.
bindings/nodejs/.editorconfig	Establishes formatting defaults for the Node bindings subtree.
bindings/nodejs/test/zot-registry.ts	Test utility to run Zot registry container for integration/push tests.
bindings/nodejs/test/tsconfig.json	TS config for running AVA tests as ES modules.
bindings/nodejs/test/package.json	Marks tests directory as ESM (`type: module`).
bindings/nodejs/test/mock-registry.ts	Mock HTTP registry server using existing Rust fixtures for deterministic tests.
bindings/nodejs/test/bindings.spec.ts	AVA test suite covering bindings behavior (auth/config/pull/push/etc.).
.github/workflows/release.yml	Gates crates.io publish on Node build/test and adds npm publish job call.
.github/workflows/nodejs-publish-call.yml	Reusable workflow to assemble artifacts and publish to npm.
.github/workflows/nodejs-build.yml	Entry workflow to run Node build/test on PRs and main branch changes.
.github/workflows/nodejs-build-call.yml	Reusable multi-platform build/test matrix for Node binaries + TS bindings.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

TerryHowe

Great work overall — the binding coverage, test setup, and multi-platform CI are well done. Inline comments cover the critical and important issues. The two blockers are the release.yml coupling (Rust publish shouldn't depend on Node.js build success) and the platform filter bug (Os::Other/Arch::Other won't match typed oci-spec variants for standard platforms like linux/amd64).

... according to review comments Signed-off-by: David Festal <dfestal@redhat.com> Assisted-by: Cursor

Signed-off-by: David Festal <dfestal@redhat.com> Assisted-by: Cursor

Signed-off-by: David Festal <dfestal@redhat.com>

to avoid building napi bindings on bare cargo commands. Signed-off-by: David Festal <dfestal@redhat.com>

Signed-off-by: David Festal <dfestal@redhat.com>

…te on dependency changes Signed-off-by: David Festal <dfestal@redhat.com>

Signed-off-by: David Festal <dfestal@redhat.com>

davidfestal · 2026-04-13T22:18:01Z

@TerryHowe I fixed all your comments.

davidfestal · 2026-04-20T21:19:55Z

@thomastaylor312 @bacongobbler @flavio any feedback on this PR ?

Done

davidfestal requested review from bacongobbler, flavio and thomastaylor312 as code owners March 31, 2026 12:29

TerryHowe requested a review from Copilot April 1, 2026 02:42

Copilot started reviewing on behalf of TerryHowe April 1, 2026 02:42 View session

Copilot AI reviewed Apr 1, 2026

View reviewed changes

TerryHowe previously requested changes Apr 1, 2026

View reviewed changes

Comment thread .github/workflows/release.yml Outdated

Comment thread bindings/nodejs/src/lib.rs Outdated

Comment thread Cargo.toml

Comment thread .github/workflows/nodejs-build-call.yml Outdated

Comment thread .github/workflows/nodejs-publish-call.yml

davidfestal added 3 commits April 2, 2026 17:18

add multi-arch tests for JS bindings...

9cf33c9

... according to review comments Signed-off-by: David Festal <dfestal@redhat.com> Assisted-by: Cursor

fix platform management after review comments

4b77ace

Signed-off-by: David Festal <dfestal@redhat.com> Assisted-by: Cursor

upgrade and pin github actions

ec83b6d

Signed-off-by: David Festal <dfestal@redhat.com>

davidfestal force-pushed the nodejs-bindings branch from 9e5610b to ec83b6d Compare April 13, 2026 19:56

davidfestal added 5 commits April 13, 2026 22:12

fix: add default-members to the main cargo.toml

36daa6b

to avoid building napi bindings on bare cargo commands. Signed-off-by: David Festal <dfestal@redhat.com>

remove unused bytes dependency from nodejs bindings

d2f8a0a

Signed-off-by: David Festal <dfestal@redhat.com>

Include nodejs binding lockfile hashes in cargo cache key to invalida…

2a3b9f8

…te on dependency changes Signed-off-by: David Festal <dfestal@redhat.com>

Decouple publishing of the main crate and the nodejs bindings

b6d5db8

Signed-off-by: David Festal <dfestal@redhat.com>

test cleanup

30898d8

Signed-off-by: David Festal <dfestal@redhat.com>

davidfestal requested a review from TerryHowe April 13, 2026 22:17

Conversation

davidfestal commented Mar 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Features:

Supported platforms (7 targets):

CI/CD:

Note:

Uh oh!

davidfestal commented Mar 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

davidfestal commented Mar 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

davidfestal commented Mar 31, 2026

Uh oh!

TerryHowe commented Mar 31, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

TerryHowe left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

davidfestal commented Apr 13, 2026

Uh oh!

davidfestal commented Apr 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

davidfestal commented Mar 31, 2026 •

edited

Loading

davidfestal commented Mar 31, 2026 •

edited

Loading

davidfestal commented Mar 31, 2026 •

edited

Loading